<?php
# ***** BEGIN LICENSE BLOCK *****
# This file is part of "myWiWall".
# Copyright (c) 2007-2008 CRP Henri Tudor and contributors.
# All rights reserved.
#
# "myWiWall" is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License version 2 as published by
# the Free Software Foundation.
# 
# "myWiWall" is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# 
# You should have received a copy of the GNU General Public License
# along with "myWiWall"; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
#
# ***** END LICENSE BLOCK *****


/**
 * The MwwException is the base class for all Exceptions thrown in the MyWiWall portal's code.
 *
 * The constructor of this class ask for its first paramter a value that represent where the exception
 * happenned (in the context of the MVC design). So, this value must be one of the following constants:
 * 
 * - MwwException::MODEL (If the error happened in the Model layer)
 * - MwwException::VIEW (If the error happened in the View layer)
 * - MwwException::ACTION (If the error happened in the Action layer)
 * 
 * As the second parameter, the constructor needs a message that must be human readable for
 * a web developper. The aim of this message is the computer scientist, not the end user !
 * 
 * As a third parameter, you can specifiy the eventual exception that is the cause of the exception
 * you are throwing (cascading exception or chained exception concept).
 * 
 * @package mywiwall.exceptions
 * @author Yannick Naudet <yannick.naudet@tudor.lu>
 */
class MwwException extends Exception {
 	
	/**
	 * Depicts the concept of a location inside the MODEL Layer.
	 *
	 */
	const MODEL = 'model';
	
	/**
	 * Depicts the concept of a location inside the VIEW layer.
	 *
	 */
 	const VIEW = 'view';
 	
 	/**
 	 * Depicts the concepts of a location inside the CONTROLLER layer.
 	 *
 	 */
 	const CONTROLLER = 'controller';
 	
 	private $loc = '<localisation not specified>';

 	/**
 	 * Creates a new instance of MwwException.
 	 * 
  	 * @param string $loc Location of the exception in the MVC framework: MODEL, VIEW, or ACTION.
  	 * @param string $message A computer scientist readable reason of the exception.
  	 * @param Exception $parentException An exception which is the cause of this one (not mandatory).
  	 * @param integer $code A code that represents the subtype of the error (not mandatory).
  	 */
  	public function __construct($loc, $message, Exception $parentException = NULL, $code = null) 
  	{
  		parent::__construct($message, $code);
  		$this->loc = $loc;
  	}
  	 
  	/**
  	 * Returns a string representation of the thrown exception in the following format:
  	 * 
  	 * "Exception_Type: [Location_In_Mvc]: Message"
  	 * i.e ServiceException: []
   	 */
  	public function __toString() {
    	return __CLASS__ . ": [{$this->loc}]: {$this->message}\n";
  	}

}
?>
